package org.dftproject.genesis.data;

import java.util.Set;

public interface IEntity {

	public Set<IAttribute> getAttributes();

	public Set<IAttribute> getAttributes(String name);

	/**
	 * Indicates whether some other entity is the "same as" this one. Note that
	 * the notion of "same as", although related, is distinct from that provided
	 * by {@link #equals}.
	 * <p>
	 * The <code>sameAs</code> method implements an equivalence relation on
	 * non-null entity references:
	 * <ul>
	 * <li>It is <i>reflexive</i>: for any non-null reference value
	 * <code>x</code>, <code>x.sameAs(x)</code> should return
	 * <code>true</code>.
	 * <li>It is <i>symmetric</i>: for any non-null reference values
	 * <code>x</code> and <code>y</code>, <code>x.sameAs(y)</code> should
	 * return <code>true</code> if and only if <code>y.sameAs(x)</code>
	 * returns <code>true</code>.
	 * <li>It is <i>transitive</i>: for any non-null reference values
	 * <code>x</code>, <code>y</code>, and <code>z</code>, if
	 * <code>x.sameAs(y)</code> returns <code>true</code> and
	 * <code>y.sameAs(z)</code> returns <code>true</code>, then
	 * <code>x.sameAs(z)</code> should return <code>true</code>.
	 * <li>It is <i>consistent</i>: for any non-null reference values
	 * <code>x</code> and <code>y</code>, multiple invocations of
	 * <code>x.sameAs(y)</code> consistently return <code>true</code> or
	 * consistently return <code>false</code>, provided no information used
	 * in <code>sameAs</code> comparisons on the entities is modified.
	 * <li>For any non-null reference value <code>x</code>,
	 * <code>x.sameAs(null)</code> should return <code>false</code>.
	 * </ul>
	 * The <code>sameAs</code> method for class <code>IEntity</code>
	 * implements the most discriminating possible equivalence relation on
	 * entities; that is, for any non-null reference values <code>x</code> and
	 * <code>y</code>, this method returns <code>true</code> if and only if
	 * <code>x</code> and <code>y</code> refer to the same entity (<code>x == y</code>
	 * has the value <code>true</code>).
	 * @param other the reference entity with which to compare
	 * @return whether this entity is the "same as" the reference entity
	 */
	public boolean sameAs(IEntity other);

	/**
	 * Returns the set of entities that this entity represents. In most cases
	 * this set will consist of only one reference, namely <code>this</code>.
	 * @return the set of entities that this entity represents
	 */
	public Set<IEntity> getEntities();

}
